home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.004 / xemacs-1 / xemacs-19.13 / src / tooltalk.doc < prev    next >
Encoding:
Text File  |  1994-09-20  |  11.6 KB  |  331 lines
  1.  
  2. Emacs Tooltalk API Summary
  3.  
  4. The Emacs Lisp interface to Tooltalk is similar, atleast in spirit,
  5. to the standard C Tootalk API.  Only the message and pattern parts
  6. of the API are supported at present, more of the API could be added
  7. if needed.  The Lisp interface departs from the C API in a few ways:
  8.  
  9. - Tooltalk is initialized automatically at emacs startup-time.  Messages
  10. can only be sent other Tooltalk applications connected to the same 
  11. X11 server that emacs is running on.  
  12.  
  13. - There are fewer entry points, polymorphic functions with keyword
  14. arguments are used instead.
  15.  
  16. - The callback interface is simpler and marginally less functional.
  17. A single callback may be associated with a message or a pattern, 
  18. the callback is specified with a Lisp symbol (the symbol should
  19. have a function binding).
  20.  
  21. - The session attribute for messages and patterns is always 
  22. initialized to the default session.
  23.  
  24. - Anywhere a Tooltalk enum constant, e.g. TT_SESSION, is valid one
  25. can substitute the corresponding symbol, e.g. 'TT_SESSION.  This
  26. simplifies building lists that represent messages and patterns.
  27.  
  28.  
  29. * Example: Receiving Messages
  30.  
  31. Here's a simple example of a handler for a message that tells
  32. emacs to display a string in the mini-buffer area.  The message
  33. operation is called "emacs-display-string", it's first (0th) argument
  34. is the string to display:
  35.  
  36. (defun tooltalk-display-string-handler (msg)
  37.   (message (get-tooltalk-message-attribute msg 'arg_val 0)))
  38.  
  39. (defvar display-string-pattern
  40.   '(category TT_HANDLE
  41.        scope TT_SESSION
  42.           op "emacs-display-string"
  43.     callback tooltalk-display-string-handler))
  44.  
  45. (let ((p (make-tooltalk-pattern display-string-pattern)))
  46.   (register-tooltalk-pattern p))
  47.  
  48.  
  49. * Example: Sending Messages
  50.  
  51. Here's a simple example that sends a query to another application
  52. and then displays it's reply.  Both the query and the reply are
  53. stored in the first argument of the message.
  54.  
  55. (defun tooltalk-random-query-handler (msg)
  56.   (let ((state (get-tooltalk-message-attribute msg 'state)))
  57.     (cond
  58.       ((eq state 'TT_HANDLED)
  59.        (message (get-tooltalk-message-attribute msg arg_val 0)))
  60.       ((memq state '(TT_FAILED TT_REJECTED))
  61.        (message "Random query turns up nothing")))))
  62.  
  63. (defvar random-query-message
  64.   '(   class TT_REQUEST 
  65.        scope TT_SESSION 
  66.      address TT_PROCEDURE
  67.           op "random-query"
  68.         args '((TT_INOUT "?" "string"))
  69.     callback tooltalk-random-query-handler))
  70.  
  71. (let ((m (make-tooltalk-message random-query-message)))
  72.   (send-tooltalk-message m))
  73.  
  74.  
  75. * Emacs Lisp Tooltalk API
  76.  
  77. ** Sending Messages:
  78.  
  79. (make-tooltalk-message attributes)
  80.  
  81. Create a tooltalk message and initialize its attributes.
  82. The value of attributes must be a list of alternating keyword/values, 
  83. where keywords are symbols that name valid message attributes.  
  84. For example:
  85.  
  86.   (make-tooltalk-message 
  87.     '(class TT_NOTICE
  88.       scope TT_SESSION
  89.       address TT_PROCEDURE
  90.       op "do-something"
  91.       args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
  92.  
  93. Values must always be strings, integers, or symbols that
  94. represent Tooltalk constants.  Attribute names are the same as 
  95. those supported by set-tooltalk-message-attribute, plus 'args.
  96.  
  97. The value of args should be a list of message arguments where
  98. each message argument has the following form:
  99.  
  100.    (mode [value [type]]) or just value
  101.  
  102. Where mode is one of TT_IN, TT_OUT, TT_INOUT and type is a string.  
  103. If type isn't specified then "int" is used if the value is a 
  104. number otherwise "string" is used.  If type is "string" then value is
  105. converted to a string (if it isn't a string already) with
  106. prin1-to-string.  If only a value is specified then mode defaults 
  107. to TT_IN.  If mode is TT_OUT then value and type don't need
  108. to be specified.  You can find out more about the semantics and 
  109. uses of ToolTalk message arguments in chapter 4 of the Tooltalk
  110. Programmers Guide.
  111.  
  112.  
  113.  
  114. (send-tooltalk-message msg)
  115.  
  116. Send the message on it's way.  Once the message has been sent it's
  117. almost always a good idea to get rid of it with destroy-tooltalk-message.
  118.  
  119.  
  120.  
  121. (return-tooltalk-message msg &optional mode)
  122.  
  123. Send a reply to this message.  The second argument can be
  124. 'reply, 'reject or 'fail, the default is 'reply.  Before sending
  125. a reply all message arguments whose mode is TT_INOUT or TT_OUT should
  126. have been filled in - see set-tooltalk-message-attribute."
  127.  
  128.  
  129.  
  130. (get-tooltalk-message-attribute msg attribute &optional argn)
  131.  
  132. Returns the indicated Tooltalk message attribute.  Attributes are
  133. identified by symbols with the same name (underscores and all) as the
  134. suffix of the Tooltalk tt_message_<attribute> function that extracts the value.
  135. String attribute values are copied, enumerated type values (except disposition)
  136. are converted to symbols - e.g. TT_HANDLER is 'TT_HANDLER, uid and gid are
  137. represented by fixnums (small integers), opnum is converted to a string,
  138. and disposition is converted to a fixnum.  We convert opnum (a C int) to a
  139. string, e.g. 123 => \"123\" because there's no guarantee that opnums will fit
  140. within the range of Emacs Lisp integers.  
  141.  
  142. [TBD] Use the 'plist attribute instead of C API 'user attribute
  143. for user defined message data.  To retrieve the value of a message property 
  144. specify the indicator for argn.  For example to get the value of a property 
  145. called 'rflagg, use
  146.    (get-tooltalk-message-attribute msg 'plist 'rflag)
  147.  
  148.  
  149. To get the value of a message argument use one of the 'arg_val (strings),
  150. 'arg_ival (integers), or 'arg_bval (strings with embedded nulls), attributes.
  151. Because integer valued arguments can be larger than Emacs Lisp integers
  152. 'arg_ival yields a string.  If the value is will fit within 24 bits then
  153. convert it to an integer with string-to-int.  For example to get the integer 
  154. value of the third argument:
  155.  
  156.    (string-to-int (get-tooltalk-message-attribute msg 'arg_ival 2))
  157.  
  158. As you can see, argument numbers are zero based.  The type of each arguments
  159. can be retrieved, with the 'arg_type attribute, however Tooltalk doesn't
  160. define any semantics for the string value of 'arg_type.  Conventionally
  161. "string" is used for strings and "int" for 32 bit integers.  Note that 
  162. Emacs Lisp stores the lengths of strings explicitly (unlike C) so treating the
  163. value returned by 'arg_bval like a string is fine.
  164.  
  165.  
  166.  
  167.  
  168. (set-tooltalk-message-attribute value msg attribute &optional argn)
  169.  
  170. Initialize one ToolTalk message attribute.
  171.  
  172. Attribue names and values are the same as for get-tooltalk-message-attribute.  
  173. A property list is provided for user data (instead of the 'user message
  174. attribute), see get-tooltalk-message-attribute.
  175.  
  176. Callbacks are handled slightly differently than in the C Tooltalk API.
  177. The value of callback should be the name of a function of one argument.
  178. It will be called each time the state of the message changes.  This
  179. is usually used to notice when the messages state has
  180. changed to TT_HANDLED (or TT_FAILED), so that reply argument values
  181. can be used.
  182.  
  183. If one of the argument attributes is specified, 'arg_val, 'arg_ival, or 
  184. 'arg_bval then argn must be the number of an already created argument.
  185. Arguments can be added to a message with add-tooltalk-message-arg.
  186.  
  187.  
  188.  
  189. (add-tooltalk-message-arg msg mode type &optional value)
  190.  
  191. Append one new argument to the message.  Mode must be one of: TT_IN,
  192. TT_INOUT, or TT_OUT, type must be a string, and value can
  193. be a string or an integer.   Tooltalk doesn't
  194. define any semantics for type, so only the participants in the
  195. protocol you're using need to agree what types mean (if anything).
  196. Conventionally "string" is used for strings and "int" for 32 bit integers.
  197. Arguments can initialized by providing a value or with
  198. set-tooltalk-message-attribute, the latter is neccessary if you
  199. want to initialize the argument with a string that can contain
  200. embedded nulls (use 'arg_bval).
  201.  
  202.  
  203. (create-tooltalk-message)
  204.  
  205. Create a new tooltalk message.  The messages session attribute is
  206. initialized to the default session.  Other attributes can be intialized
  207. with set-tooltalk-message-attribute.  Make-tooltalk-message is the
  208. preferred to create and initialize a message.
  209.  
  210.  
  211. (destroy-tooltalk-message msg)
  212.  
  213. Apply tt_message_destroy to the message.  It's not neccessary
  214. to destroy messages after they've been proccessed by a message or 
  215. pattern callback, the Lisp/Tooltalk callback machinery does this
  216. for you.
  217.  
  218.  
  219.  
  220. ** Receiving Messages:
  221.  
  222.  
  223. (make-tooltalk-pattern attributes)
  224.  
  225. Create a tooltalk pattern and initialize its attributes.
  226. The value of attributes must be a list of alternating keyword/values, 
  227. where keywords are symbols that name valid pattern attributes
  228. or lists of valid attributes.  For example:
  229.  
  230.   (make-tooltalk-pattern 
  231.     '(category TT_OBSERVE
  232.          scope TT_SESSION
  233.             op ("operation1" "operation2")
  234.           args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
  235.  
  236. Attribute names are the same as those supported by 
  237. add-tooltalk-pattern-attribute, plus 'args.
  238.  
  239. Values must always be strings, integers, or symbols that
  240. represent Tooltalk constants or lists of same.  When a list 
  241. of values is provided all of the list elements are added to 
  242. the attribute.  In the example above, messages whose op
  243. attribute is "operation1" or "operation2" would match the pattern.
  244.  
  245. The value of args should be a list of pattern arguments where 
  246. each pattern argument has the following form:
  247.  
  248.    (mode [value [type]]) or just value
  249.  
  250. Where mode is one of TT_IN, TT_OUT, TT_INOUT and type is a string.  
  251. If type isn't specified then "int" is used if the value is a 
  252. number otherwise "string" is used.  If type is "string" then value is
  253. converted to a string (if it isn't a string already) with
  254. prin1-to-string.  If only a value is specified then mode defaults 
  255. to TT_IN.  If mode is TT_OUT then value and type don't need
  256. to be specified.  You can find out more about the semantics and 
  257. uses of ToolTalk pattern arguments in chapter 3 of the Tooltalk
  258. Programmers Guide.
  259.  
  260.  
  261.  
  262. (register-tooltalk-pattern pat)
  263.  
  264. Emacs will begin receiving messages that match this pattern.
  265.  
  266.  
  267. (unregister-tooltalk-pattern pat)
  268.  
  269. Emacs will stop receiving messages that match this pattern.
  270.  
  271.  
  272.  
  273. (add-tooltalk-pattern-attribute value pat indicator)
  274.  
  275. Add one value to the indicated pattern attribute. The names of attributes
  276. are the same as the Tooltalk accessors used to set them less the 
  277. "tooltalk_pattern_" prefix and the "_add" suffix).  For example 
  278. the name of the attribute for tt_pattern_dispostion_add attribute 
  279. is 'disposition.  The 'category attribute is handled specially, 
  280. since a pattern can only be a member of one category (TT_OBSERVE
  281. or TT_HANDLE.
  282.  
  283. Callbacks are handled slightly differently than in the C Tooltalk API.
  284. The value of callback should be the name of a function of one argument.
  285. It will be called each time the pattern matches an incoming message. 
  286.  
  287.  
  288.  
  289. (add-tooltalk-pattern-arg pat mode type value)
  290.  
  291. Add one, fully specified, argument to a tooltalk pattern.  Mode must 
  292. be one of TT_IN, TT_INOUT, or TT_OUT, type must be a string.
  293. Value can be an integer, string or nil.  If value is an integer then 
  294. an integer argument (tt_pattern_iarg_add) added otherwise a string argument
  295. is added.  At present there's no way to add a binary data argument.
  296.  
  297.  
  298. (create-tooltalk-pattern)
  299.  
  300. Create a new Tooltalk pattern and initialize its session attribute to
  301. be the default session.
  302.  
  303.  
  304.  
  305. (destroy-tooltalk-pattern pat)
  306.  
  307. Apply tt_pattern_destroy to the pattern.  This effecticely unregisters
  308. the pattern.
  309.  
  310.  
  311.  
  312. (describe-tooltalk-message msg &optional stream)
  313.  
  314. Print the messages attributes and arguments to stream.  This is often
  315. useful for debugging.
  316.  
  317.  
  318.  
  319. * Things to be Done
  320.  
  321. - At the moment there is almost no support for detecting and
  322. handling ToolTalk errors.  This should be added.
  323.  
  324. - Message and patterns should support a plist attribute.  This
  325. would be based on one more Tooltalk user data key.  This would also make
  326. it useful to apply the message and pattern callbacks to 
  327. both the message and the matching pattern.
  328.  
  329.  
  330.  
  331.